/*
 * MIT License
 *
 * Copyright (c) 2025 Mark·虎
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 */

package com.hsxxherp.key.uia.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.hsxxherp.key.uia.entity.SysApplicationGroup;
import org.springframework.transaction.annotation.Transactional;

/**
 * 应用分组服务接口，定义了对应用分组进行增删改查等操作的方法。
 * 该接口继承自 MyBatis-Plus 的 IService 接口，可使用其提供的通用服务方法。
 *
 * @author Mark·虎（2486970363@qq.com）
 */
public interface ISysApplicationGroupService extends IService<SysApplicationGroup> {

    /**
     * 插入或创建一个新的应用分组。
     * 此方法会检查要插入的应用分组名称是否已存在，如果存在则抛出异常，
     * 若不存在则将应用分组信息保存到数据库，并返回插入后的应用分组实体。
     *
     * @param sysApplicationGroup 要插入或创建的应用分组实体，包含应用分组的各项信息，如分组名称、描述等。
     * @return 插入成功后返回插入的应用分组实体，若插入失败则可能抛出异常或返回 null（具体取决于实现）。
     */
    SysApplicationGroup insertOrCreateApplicationGroup(SysApplicationGroup sysApplicationGroup);

    /**
     * 更新一个已存在的应用分组信息。
     * 此方法会先检查要修改的应用分组是否存在，若不存在则抛出异常；
     * 接着检查修改后的应用分组名称是否与其他已存在的分组名称重复（排除当前要修改的分组），若重复则抛出异常；
     * 若检查通过，则执行更新操作，并返回更新后的应用分组实体。
     * 该方法使用了事务管理，若操作过程中出现异常，会进行回滚操作。
     *
     * @param sysApplicationGroup 包含要更新的应用分组信息的实体，其中应包含应用分组的 ID 以及要更新的字段。
     * @return 更新成功后返回更新后的应用分组实体，若更新失败则可能抛出异常或返回 null（具体取决于实现）。
     */
    @Transactional(rollbackFor = Exception.class)
    SysApplicationGroup updateApplicationGroup(SysApplicationGroup sysApplicationGroup);

    /**
     * 删除一个已存在的应用分组。
     * 此方法会先检查要删除的应用分组是否存在，若不存在则抛出异常；
     * 然后检查该分组下是否存在关联的应用，若存在则抛出异常，防止删除有应用关联的分组；
     * 若检查通过，则执行软删除操作（将 `deleted` 字段标记为 `true`）。
     * 该方法使用了事务管理，若操作过程中出现异常，会进行回滚操作。
     *
     * @param groupId 要删除的应用分组的唯一标识。
     * @return 删除成功返回 true，失败返回 false 或抛出异常（具体取决于实现）。
     */
    @Transactional(rollbackFor = Exception.class)
    boolean deleteApplicationGroup(String groupId);
}